/OpenDoc/Developer Documentation/HTML/HTML documents/ODClassRef/graphics/level3.gif/level3.gif)
/OpenDoc/Developer Documentation/HTML/HTML documents/ODClassRef/prev.gif)
/OpenDoc/Developer Documentation/HTML/HTML documents/ODClassRef/content.gif)
/OpenDoc/Developer Documentation/HTML/HTML documents/ODClassRef/index.gif)
/OpenDoc/Developer Documentation/HTML/HTML documents/ODClassRef/next.gif)
ODStorageUnit
- Superclasses
ODRefCntObject-->ODObject- Subclasses
- none
An object of the
ODStorageUnitclass represents the basic unit of persistent storage.Description
TheODStorageUnitclass is implemented differently for different platforms and storage mechanisms.The set of related classes,
ODContainer(page 98),ODDocument(page 132),ODDraft(page 147), andODStorageUnitis called a container suite. Container suite classes are implemented as an integrated set for each platform and storage mechanism because they work intimately with one another at many levels. The container suite used by default on the Mac OS platform is the Bento container suite.Every persistent object has an associated storage unit where it stores its data persistently. Storage units are also used for data-transfer operations; the clipboard and the drag-and-drop objects each have a content storage unit where they store the data to be transferred. Because storage units may no longer be valid as soon as a data transfer is complete, you should never cache a reference to a data-transfer object's storage unit.
Your part creates a new storage unit by calling its draft's
CreateStorageUnitmethod (page 170); it accesses an existing storage unit by calling its draft'sAcquireStorageUnitmethod (page 158).A storage unit consists of one or more properties, each of which has a unique name within the storage unit and is distinguished by the kind of information it contains (such as, "name" or "content"). For example, the properties in your part's storage unit are used to store persistently both the content of your part and also supplemental information. OpenDoc defines a standard set of properties for all parts; you can define additional properties for information specific to your particular part. A property consists of one or more data streams, called values, each of which has a named type. Each property can have only one value of a given type.
In a data-transfer operation, the source part writes data to one or more values of the data-transfer object's content storage unit; the destination part reads from those values. The source part can write either the data to be transferred, or a promise, which is a specification of data to be transferred at a future time. A value that contains promise data is called a promise value; a value that does not contain promise data is called a regular value. When and if a destination tries to read the promise, the storage unit first resolves the promise by asking the source part to fulfill it. The source part fulfills the promise by replacing the promise in the storage unit with the actual data that was promised.
OpenDoc assigns a runtime identifier, a storage-unit ID, to each of its storage units. A storage-unit ID is a nonpersistent identifier for a storage unit that is unique within its draft (storage-unit IDs are not unique across drafts and do not persist across sessions). You can use the storage-unit ID to identify storage units and to compare two storage units for equality. The ID of the storage unit for a persistent object is also used as the ID of the object itself. If you retain the ID of a persistent object when you release it, you can use that ID to re-create the object from the data stored in its storage unit. For example, when a frame is scrolled out of view, you can save its ID and release it; if the frame is later scrolled back into view, you can obtain a reference to it by passing the saved ID to the draft's
AcquireFramemethod (page 153). If the frame has been purged since you released it, theAcquireFramemethod re-creates it from its stored data.Storage units can maintain persistent references to other storage units in the same draft. A persistent reference stored in a storage unit value is an opaque type that identifies another storage unit in the same draft. Whereas the ID of a storage unit identifies that storage unit within the current session, a persistent reference to the storage unit identifies it persistently across sessions. Persistent references permit complex runtime relationships between objects to be stored externally and later reconstructed; for example, the embedding relationships of the parts within a draft are preserved by persistent references in the parts' storage units. Persistent references can be either strong or weak. In a clone operation, copies are made of all storage units referenced by strong persistent references in the object being cloned. A weak persistent reference is typically ignored during cloning; however, if a storage unit is cloned because there are strong persistent references to it, then weak persistent references to the storage unit are preserved.
OpenDoc allows you to focus a storage unit on the particular data of interest, called the focus context. Before reading or writing to a storage unit, for example, you must focus on the data stream defined by a particular value of a particular property. At any time the storage unit can be in one of the following states:
To define a focus context, you can specify a property by its name or a position code. Within a given property, you can specify the value of interest by a value type, a position code, or a value index. A position code is a constant that specifies either an absolute position for the property or value or a position relative to the property or value in the current focus context. Position codes allow you to access the next or previous property within the set of properties in a storage unit or the next or previous value within the set of values in the same property. A value index is a number representing the ordinal position of the value within the property. The first value created for a property has index 1; the second, 2; and so on.
- Unfocused. When a storage unit is unfocused, its focus context is undefined.
- Focused on the entire storage unit. When the focus context is the storage unit, the data of interest includes all properties and all their values.
- Focused on a particular property. When the focus context is a property, the data of interest includes all values of the focused property.
- Focused on a particular value of a particular property. When the focus context is a value, the data of interest is the data stream corresponding to a focused value.
When the storage unit is focused on a value of a property, you can read data from and write data to the corresponding data stream. The storage unit has a zero-based offset that specifies the current read/write position in the stream. When the storage unit is first focused, the offset is 0, indicating the beginning of the stream. Each read and write advances the offset by the number of bytes that were read or written. The storage unit also has methods that allow you to get and set the current offset.
You can call methods of a storage unit to create related objects that make it easy to work with the data in the storage unit.
For more information about these objects, see the descriptions of the classes
- A storage-unit view represents the storage unit prefocused on a particular focus context. You can pass a storage-unit view among your software components to give them access to the particular focused data stream.
- A storage-unit cursor represents a focus context. You can create storage-unit cursors for focus contexts that you access frequently, then use those cursors to switch the focus from one context to another.
- A storage-unit reference iterator allows you to access all persistent references in the currently focused value of the storage unit.
ODStorageUnitView(page 725),ODStorageUnitCursor(page 716), andODStorageUnitRefIterator(page 721).Methods
This section presents summary descriptions of theODStorageUnitmethods grouped according to purpose, followed by detailed descriptions in alphabetical order.
Access and Storage
Lock- Locks this storage unit for exclusive access.
Unlock- Unlocks this storage unit.
CloneInto- Copies all properties and values of this storage unit to the specified destination storage unit.
Externalize- Resolves all promises in this storage unit and saves all its properties and values to persistent, external storage.
Internalize- Reads all properties and values from this storage unit into memory.
Storage Unit Manipulation
AddProperty- Adds a property with the specified name to this storage unit.
AddValue- Adds a value of the specified type to the currently focused property.
Remove- Removes all properties and values in the current focus context from this storage unit.
CountProperties- Returns the number of properties in this storage unit.
CountValues- Returns the number of values in the current focus context for this storage unit.
GetID- Returns the storage-unit ID for this storage unit.
GetName- Returns the name of this storage unit.
SetName- Sets the name of this storage unit.
GetSize- Returns the size (number of bytes) of the data in the current focus context.
Focus Manipulation
Exists- Returns a Boolean value that indicates whether the specified focus context exists in this storage unit.
ExistsWithCursor- Returns a Boolean value that indicates whether the focus context represented by the specified storage-unit cursor exists in this storage unit.
Focus- Focuses this storage unit on the specified focus context.
FocusWithCursor- Focuses this storage unit on the focus context represented by the specified storage-unit cursor.
GetProperty- Returns the name of the property in the current focus context.
Value Manipulation
GetValue- Reads data from the currently focused value, starting at the offset (inclusive).
SetValue- Writes data to the currently focused value, starting at the offset (inclusive).
DeleteValue- Deletes data from the currently focused value, starting at the offset (inclusive).
InsertValue- Inserts data into the currently focused value, starting at the offset (inclusive).
GetOffset- Returns the offset of the currently focused value.
SetOffset- Sets the offset of the currently focused value.
GetType- Returns the type of the currently focused value.
SetType- Sets the type of the currently focused value.
GetGenerationNumber- Returns the generation number of the currently focused value.
IncrementGenerationNumber- Increments and returns the generation number of the currently focused value.
Persistent Reference Manipulation
GetIDFromStorageUnitRef- Returns the storage-unit ID of a referenced storage unit.
GetStrongStorageUnitRef- Creates a strong persistent reference to the specified storage unit.
GetWeakStorageUnitRef- Creates a weak persistent reference to the specified storage unit.
IsStrongStorageUnitRef- Returns a Boolean value that indicates whether the specified persistent reference is a strong persistent reference.
IsWeakStorageUnitRef- Returns a Boolean value that indicates whether the specified persistent reference is a weak persistent reference.
IsValidStorageUnitRef- Returns a Boolean value that indicates whether the specified persistent reference is valid.
SetStorageUnitRef- Creates in the currently focused value a persistent reference to the specified storage unit using the specified the persistent identifier.
RemoveStorageUnitRef- Makes a persistent reference invalid in the currently focused value.
Promise Manipulation
IsPromiseValue- Returns a Boolean value that indicates whether the currently focused value is a promise value.
GetPromiseValue- Reads promise data from the specified value of the currently focused property.
SetPromiseValue- Writes data to the specified value of the currently focused property, creating the value if it doesn't exist and making the value a promise value.
ClearAllPromises- Changes all promise values in this storage unit into regular values.
ResolveAllPromises- Resolves all promises in this storage unit.
Creating Objects
CreateCursor- Creates a storage-unit cursor representing the specified focus context for this storage unit.
CreateCursorWithFocus- Creates a storage-unit cursor representing the current focus context of this storage unit.
CreateStorageUnitRefIterator- Creates a storage-unit reference iterator for the currently focused value.
CreateView- Creates a storage-unit view for this storage unit with its current focus context.
Utility Routines
GetDraft- Returns a reference to the draft object that created this storage unit.
GetSession- Returns a reference to the session object in which this storage unit runs.
Methods
AddProperty
AddValue
ClearAllPromises
CloneInto
CountProperties
CountValues
CreateCursor
CreateCursorWithFocus
CreatStorageUnitRefIterator
CreateView
DeleteValue
Exists
ExistsWithCursor
Externalize
Focus
FocusWithCursor
GetDraft
GetGenerationNumber
GetID
GetIDFromStorageUnitRef
GetName
GetOffset
GetPromiseValue
GetProperty
GetSession
GetSize
GetStrongStorageUnitRef
GetType
GetValue
GetWeakStorageUnitRef
IncrementGenerationNumber
InsertValue
Internalize
IsPromiseValue
IsStrongStorageUnitRef
IsValidStorageUnitRef
IsWeakStorageUnitRef
Lock
Remove
RemoveStorageUnitRef
ResolveAllPromises
SetName
SetOffset
SetPromiseValue
SetStorageUnitRef
SetType
SetValue
Unlock
/OpenDoc/Developer Documentation/HTML/HTML documents/ODClassRef/graphics/nav.gif/nav.gif){kind=small}
Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help